I ve been subscribed to the
Git mailinglist for three weeks
now, and I ve finally seen in action what was already imaginable by
looking at their
git log history: they not only review the code for
the patches that go in (as in many other projects, that is), but also
review the accompanying commit messages, in order to ensure they meet
certain quality standards. More than once already I ve seen an
otherwise-fine patch get resubmitted in order to gain a more meaningful
or thorough commit message.
I m sure there are more projects that do this, but alas, I haven t been
in any of them (nor in that many projects in general, for that matter).
It s very exciting for me to see it in action, because quality commit
messages are high in my Grokking VCS list.
Ideally, a commit message conveys all the necessary information the
maintainer of a project needs to understand your patch and its benefits,
in particular those bits that don t fit as comments in the code. If you
have to accompany your patch with rationales, wouldn t it make sense to
include a condensed version of them in your commit message? If you re
writing messages for a project of your own, please think of future
people dealing with your code, particularly if it s a public project.
(It takes discipline in addition to being convinced of it, though.)
Commit messages are also great because they allow you to be verbose,
without cluttering the code with information that s only relevant in the
context of the change, and not to the final code. There is however an
(actually-not-so-fine) line between what should be in the commit
message, and what should be as comments in the code, and I think we
commit message enthusiasts should watch out for that. Take, for example,
39c19ce. I think a short comment saying Don t call rev-parse for
each blamed line would have been a perfect companion.
There must be somewhere a document explaining with more detail what
makes a good commit message. If you would recommend any, please
let me
know (but I m not interested in documents
that explain how to
format your commit messages).